home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / signals.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  11KB  |  321 lines
  1. /**
  2.  * @file signals.h Signal API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_SIGNALS_H_
  26. #define _GAIM_SIGNALS_H_
  27.  
  28. #include <glib.h>
  29. #include "value.h"
  30.  
  31. #define GAIM_CALLBACK(func) ((GaimCallback)func)
  32.  
  33. typedef void (*GaimCallback)(void);
  34. typedef void (*GaimSignalMarshalFunc)(GaimCallback cb, va_list args,
  35.                                       void *data, void **return_val);
  36.  
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40.  
  41. /**************************************************************************/
  42. /** @name Signal API                                                      */
  43. /**************************************************************************/
  44. /*@{*/
  45.  
  46. /**
  47.  * Signal Connect Priorities
  48.  */
  49. #define GAIM_SIGNAL_PRIORITY_DEFAULT     0
  50. #define GAIM_SIGNAL_PRIORITY_HIGHEST  9999
  51. #define GAIM_SIGNAL_PRIORITY_LOWEST  -9999
  52.  
  53. /**
  54.  * Registers a signal in an instance.
  55.  *
  56.  * @param instance   The instance to register the signal for.
  57.  * @param signal     The signal name.
  58.  * @param marshal    The marshal function.
  59.  * @param ret_value  The return value type, or NULL for no return value.
  60.  * @param num_values The number of values to be passed to the callbacks.
  61.  * @param ...        The values to pass to the callbacks.
  62.  *
  63.  * @return The signal ID local to that instance, or 0 if the signal
  64.  *         couldn't be registered.
  65.  *
  66.  * @see GaimValue
  67.  */
  68. gulong gaim_signal_register(void *instance, const char *signal,
  69.                             GaimSignalMarshalFunc marshal,
  70.                             GaimValue *ret_value, int num_values, ...);
  71.  
  72. /**
  73.  * Unregisters a signal in an instance.
  74.  *
  75.  * @param instance The instance to unregister the signal for.
  76.  * @param signal   The signal name.
  77.  */
  78. void gaim_signal_unregister(void *instance, const char *signal);
  79.  
  80. /**
  81.  * Unregisters all signals in an instance.
  82.  *
  83.  * @param instance The instance to unregister the signal for.
  84.  */
  85. void gaim_signals_unregister_by_instance(void *instance);
  86.  
  87. /**
  88.  * Returns a list of value types used for a signal.
  89.  *
  90.  * @param instance   The instance the signal is registered to.
  91.  * @param signal     The signal.
  92.  * @param ret_value  The return value from the last signal handler.
  93.  * @param num_values The returned number of values.
  94.  * @param values     The returned list of values.
  95.  */
  96. void gaim_signal_get_values(void *instance, const char *signal,
  97.                             GaimValue **ret_value,
  98.                             int *num_values, GaimValue ***values);
  99.  
  100. /**
  101.  * Connects a signal handler to a signal for a particular object.
  102.  *
  103.  * Take care not to register a handler function twice. Gaim will
  104.  * not correct any mistakes for you in this area.
  105.  *
  106.  * @param instance The instance to connect to.
  107.  * @param signal   The name of the signal to connect.
  108.  * @param handle   The handle of the receiver.
  109.  * @param func     The callback function.
  110.  * @param data     The data to pass to the callback function.
  111.  * @param priority The order in which the signal should be added to the list
  112.  *
  113.  * @return The signal handler ID.
  114.  *
  115.  * @see gaim_signal_disconnect()
  116.  */
  117. gulong gaim_signal_connect_priority(void *instance, const char *signal,
  118.                    void *handle, GaimCallback func, void *data, int priority);
  119.  
  120. /**
  121.  * Connects a signal handler to a signal for a particular object.
  122.  * (priority defaults to 0)
  123.  * 
  124.  * Take care not to register a handler function twice. Gaim will
  125.  * not correct any mistakes for you in this area.
  126.  *
  127.  * @param instance The instance to connect to.
  128.  * @param signal   The name of the signal to connect.
  129.  * @param handle   The handle of the receiver.
  130.  * @param func     The callback function.
  131.  * @param data     The data to pass to the callback function.
  132.  *
  133.  * @return The signal handler ID.
  134.  *
  135.  * @see gaim_signal_disconnect()
  136.  */
  137. gulong gaim_signal_connect(void *instance, const char *signal,
  138.                            void *handle, GaimCallback func, void *data);
  139.  
  140. /**
  141.  * Connects a signal handler to a signal for a particular object.
  142.  *
  143.  * The signal handler will take a va_args of arguments, instead of
  144.  * individual arguments.
  145.  *
  146.  * Take care not to register a handler function twice. Gaim will
  147.  * not correct any mistakes for you in this area.
  148.  *
  149.  * @param instance The instance to connect to.
  150.  * @param signal   The name of the signal to connect.
  151.  * @param handle   The handle of the receiver.
  152.  * @param func     The callback function.
  153.  * @param data     The data to pass to the callback function.
  154.  * @param priority The order in which the signal should be added to the list
  155.  *
  156.  * @return The signal handler ID.
  157.  *
  158.  * @see gaim_signal_disconnect()
  159.  */
  160. gulong gaim_signal_connect_priority_vargs(void *instance, const char *signal,
  161.                     void *handle, GaimCallback func, void *data, int priority);
  162.  
  163. /**
  164.  * Connects a signal handler to a signal for a particular object.
  165.  * (priority defaults to 0)
  166.  * The signal handler will take a va_args of arguments, instead of
  167.  * individual arguments.
  168.  *
  169.  * Take care not to register a handler function twice. Gaim will
  170.  * not correct any mistakes for you in this area.
  171.  *
  172.  * @param instance The instance to connect to.
  173.  * @param signal   The name of the signal to connect.
  174.  * @param handle   The handle of the receiver.
  175.  * @param func     The callback function.
  176.  * @param data     The data to pass to the callback function.
  177.  *
  178.  * @return The signal handler ID.
  179.  *
  180.  * @see gaim_signal_disconnect()
  181.  */
  182. gulong gaim_signal_connect_vargs(void *instance, const char *signal,
  183.                                  void *handle, GaimCallback func, void *data);
  184.  
  185. /**
  186.  * Disconnects a signal handler from a signal on an object.
  187.  *
  188.  * @param instance The instance to disconnect from.
  189.  * @param signal   The name of the signal to disconnect.
  190.  * @param handle   The handle of the receiver.
  191.  * @param func     The registered function to disconnect.
  192.  *
  193.  * @see gaim_signal_connect()
  194.  */
  195. void gaim_signal_disconnect(void *instance, const char *signal,
  196.                             void *handle, GaimCallback func);
  197.  
  198. /**
  199.  * Removes all callbacks associated with a receiver handle.
  200.  *
  201.  * @param handle The receiver handle.
  202.  */
  203. void gaim_signals_disconnect_by_handle(void *handle);
  204.  
  205. /**
  206.  * Emits a signal.
  207.  *
  208.  * @param instance The instance emitting the signal.
  209.  * @param signal   The signal being emitted.
  210.  *
  211.  * @see gaim_signal_connect()
  212.  * @see gaim_signal_disconnect()
  213.  */
  214. void gaim_signal_emit(void *instance, const char *signal, ...);
  215.  
  216. /**
  217.  * Emits a signal, using a va_list of arguments.
  218.  *
  219.  * @param instance The instance emitting the signal.
  220.  * @param signal   The signal being emitted.
  221.  * @param args     The arguments list.
  222.  *
  223.  * @see gaim_signal_connect()
  224.  * @see gaim_signal_disconnect()
  225.  */
  226. void gaim_signal_emit_vargs(void *instance, const char *signal, va_list args);
  227.  
  228. /**
  229.  * Emits a signal and returns the return value from the last handler.
  230.  *
  231.  * @param instance The instance emitting the signal.
  232.  * @param signal   The signal being emitted.
  233.  *
  234.  * @return The return value from the last handler.
  235.  */
  236. void *gaim_signal_emit_return_1(void *instance, const char *signal, ...);
  237.  
  238. /**
  239.  * Emits a signal and returns the return value from the last handler.
  240.  *
  241.  * @param instance The instance emitting the signal.
  242.  * @param signal   The signal being emitted.
  243.  * @param args     The arguments list.
  244.  *
  245.  * @return The return value from the last handler.
  246.  */
  247. void *gaim_signal_emit_vargs_return_1(void *instance, const char *signal,
  248.                                       va_list args);
  249.  
  250. /**
  251.  * Initializes the signals subsystem.
  252.  */
  253. void gaim_signals_init();
  254.  
  255. /**
  256.  * Uninitializes the signals subsystem.
  257.  */
  258. void gaim_signals_uninit();
  259.  
  260. /*@}*/
  261.  
  262. /**************************************************************************/
  263. /** @name Marshal Functions                                               */
  264. /**************************************************************************/
  265. /*@{*/
  266.  
  267. void gaim_marshal_VOID(
  268.         GaimCallback cb, va_list args, void *data, void **return_val);
  269. void gaim_marshal_VOID__INT(
  270.         GaimCallback cb, va_list args, void *data, void **return_val);
  271. void gaim_marshal_VOID__INT_INT(
  272.         GaimCallback cb, va_list args, void *data, void **return_val);
  273. void gaim_marshal_VOID__POINTER(
  274.         GaimCallback cb, va_list args, void *data, void **return_val);
  275. void gaim_marshal_VOID__POINTER_UINT(
  276.         GaimCallback cb, va_list args, void *data, void **return_val);
  277. void gaim_marshal_VOID__POINTER_POINTER(
  278.         GaimCallback cb, va_list args, void *data, void **return_val);
  279. void gaim_marshal_VOID__POINTER_POINTER_UINT(
  280.         GaimCallback cb, va_list args, void *data, void **return_val);
  281. void gaim_marshal_VOID__POINTER_POINTER_UINT_UINT(
  282.         GaimCallback cb, va_list args, void *data, void **return_val);
  283. void gaim_marshal_VOID__POINTER_POINTER_POINTER(
  284.         GaimCallback cb, va_list args, void *data, void **return_val);
  285. void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER(
  286.         GaimCallback cb, va_list args, void *data, void **return_val);
  287. void gaim_marshal_VOID__POINTER_POINTER_POINTER_POINTER_POINTER(
  288.         GaimCallback cb, va_list args, void *data, void **return_val);
  289. void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT(
  290.         GaimCallback cb, va_list args, void *data, void **return_val);
  291. void gaim_marshal_VOID__POINTER_POINTER_POINTER_UINT_UINT(
  292.         GaimCallback cb, va_list args, void *data, void **return_val);
  293.  
  294. void gaim_marshal_INT__INT(
  295.         GaimCallback cb, va_list args, void *data, void **return_val);
  296. void gaim_marshal_INT__INT_INT(
  297.         GaimCallback cb, va_list args, void *data, void **return_val);
  298.  
  299. void gaim_marshal_BOOLEAN__POINTER(
  300.         GaimCallback cb, va_list args, void *data, void **return_val);
  301. void gaim_marshal_BOOLEAN__POINTER_POINTER(
  302.         GaimCallback cb, va_list args, void *data, void **return_val);
  303. void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER(
  304.         GaimCallback cb, va_list args, void *data, void **return_val);
  305. void gaim_marshal_BOOLEAN__POINTER_POINTER_UINT(
  306.         GaimCallback cb, va_list args, void *data, void **return_val);
  307. void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_UINT(
  308.         GaimCallback cb, va_list args, void *data, void **return_val);
  309. void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER(
  310.         GaimCallback cb, va_list args, void *data, void **return_val);
  311. void gaim_marshal_BOOLEAN__POINTER_POINTER_POINTER_POINTER_POINTER(
  312.         GaimCallback cb, va_list args, void *data, void **return_val);
  313.  
  314. /*@}*/
  315.  
  316. #ifdef __cplusplus
  317. }
  318. #endif
  319.  
  320. #endif /* _GAIM_SIGNALS_H_ */
  321.